---
title: Sparkline
icon: '#pro/Spline'
---

<MetaData
  lang="en-US"
  isPro
  meta={{
    preset: [{
      client: '@univerjs/preset-sheets-advanced',
      locale: '@univerjs/preset-sheets-advanced/locales/en-US',
      style: '@univerjs/preset-sheets-advanced/lib/index.css',
    }],
    plugins: [{
      client: '@univerjs-pro/sheets-sparkline',
      facade: '@univerjs-pro/sheets-sparkline/facade',
    }, {
      client: '@univerjs-pro/sheets-sparkline-ui',
      locale: '@univerjs-pro/sheets-sparkline-ui/locale/en-US',
      style: '@univerjs-pro/sheets-sparkline-ui/lib/index.css',
    }],
    server: 'No',
  }}
/>

Sparkline is a compact, inline chart that provides a visual representation of data trends or key metrics, typically embedded within a table cell.

## Preset Mode

The sparkline feature is included in the `@univerjs/preset-sheets-advanced` preset.

### Installation

<Callout>
  The `UniverSheetsAdvancedPreset` preset from `@univerjs/preset-sheets-advanced` depends on the `UniverSheetsDrawingPreset` preset at runtime. Please install `@univerjs/preset-sheets-drawing` first.
</Callout>

```package-install
npm install @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

### Usage

```typescript
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced' // [!code ++]
import UniverPresetSheetsAdvancedEnUS from '@univerjs/preset-sheets-advanced/locales/en-US' // [!code ++]
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'
import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing' // [!code ++]
import UniverPresetSheetsDrawingEnUS from '@univerjs/preset-sheets-drawing/locales/en-US' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-drawing/lib/index.css' // [!code ++]
import '@univerjs/preset-sheets-advanced/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.En_US,
  locales: {
    [LocaleType.En_US]: mergeLocales(
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsDrawingEnUS, // [!code ++]
      UniverPresetSheetsAdvancedEnUS, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsDrawingPreset(), // [!code ++]
    UniverSheetsAdvancedPreset(), // [!code ++]
  ],
})
```

If you have a commercial license for Univer, please refer to [Using License in Client](/guides/pro/license#in-preset-mode) for configuration.

{/* ### Presets and Configuration */}

## Plugin Mode

### Installation

```package-install
npm install @univerjs-pro/sheets-sparkline @univerjs-pro/sheets-sparkline-ui
```

### Usage

```typescript
import { UniverSheetSparklinePlugin } from '@univerjs-pro/sheets-sparkline' // [!code ++]
import { UniverSheetSparklineUIPlugin } from '@univerjs-pro/sheets-sparkline-ui' // [!code ++]
import SheetsSparklineUIEnUS from '@univerjs-pro/sheets-sparkline-ui/locale/en-US' // [!code ++]
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'

import '@univerjs-pro/sheets-sparkline/facade' // [!code ++]

import '@univerjs-pro/sheets-sparkline-ui/lib/index.css' // [!code ++]

const univer = new Univer({
  locale: LocaleType.En_US,
  locales: {
    [LocaleType.En_US]: mergeLocales(
      SheetsSparklineUIEnUS, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverSheetSparklinePlugin)
univer.registerPlugin(UniverSheetSparklineUIPlugin)
```

If you have a commercial license for Univer, please refer to [Using License in Client](/guides/pro/license#in-plugin-mode) for configuration.

## Facade API

### Add Sparkline

[`FWorksheet.addSparkline`](https://reference.univer.ai/en-US/classes/FWorksheet#addsparkline) method is used to add a sparkline in the specified range, returning an `FSparkline` instance.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Create a sparkline with data source from A1:A7, placed in cell A10.
const sourceRanges = [fWorksheet.getRange('A1:A7').getRange()]
const targetRanges = [fWorksheet.getRange('A10').getRange()]
const sparkline = fWorksheet.addSparkline(sourceRanges, targetRanges, univerAPI.Enum.SparklineTypeEnum.LINE_CHART)
```

### Compose and Uncomposing Sparkline

[`FWorksheet.composeSparkline`](https://reference.univer.ai/en-US/classes/FWorksheet#composesparkline) and [`FWorksheet.unComposeSparkline`](https://reference.univer.ai/en-US/classes/FWorksheet#uncomposesparkline) methods are used to compose and uncompose sparklines.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Create a sparkline with data source from A1:A7, placed in cell A10.
const firstSparkline = fWorksheet.addSparkline(
  [fWorksheet.getRange('A1:A7').getRange()],
  [fWorksheet.getRange('A10').getRange()],
)

// Create a sparkline with data source from B1:B7, placed in cell B10.
const secondSparkline = fWorksheet.addSparkline(
  [fWorksheet.getRange('B1:B7').getRange()],
  [fWorksheet.getRange('B10').getRange()],
)

// Compose the two sparklines into a sparkline group
fWorksheet.composeSparkline([fWorksheet.getRange('A10:B10').getRange()])
console.log(fWorksheet.getAllSubSparkline().size) // 1

// After 3 seconds, uncompose the sparkline group
setTimeout(() => {
  fWorksheet.unComposeSparkline([fWorksheet.getRange('A10:B10').getRange()])
  console.log(fWorksheet.getAllSubSparkline().size) // 2
}, 3000)
```

### Get Sparkline and Sparkline Group Instances

[`FWorksheet.getSparklineByCell`](https://reference.univer.ai/en-US/classes/FWorksheet#getsparklinebycell) is used to get the sparkline instance in a specified cell, returning an `FSparkline` instance.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Create a sparkline with data source from A1:A7, placed in cell A10.
const sourceRanges = [fWorksheet.getRange('A1:A7').getRange()]
const targetRanges = [fWorksheet.getRange('A10').getRange()]
const sparkline = fWorksheet.addSparkline(sourceRanges, targetRanges)

console.log('Cell A10: ', fWorksheet.getSparklineByCell(9, 0))
console.log('Cell A11: ', fWorksheet.getSparklineByCell(10, 0))
```

[`FWorksheet.getSparklineGroupByCell`](https://reference.univer.ai/en-US/classes/FWorksheet#getsparklinegroupbycell) is used to get the sparkline group instance in a specified cell, returning an `FSparklineGroup` instance.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Create a sparkline with data source from A1:A7, placed in cell A10.
const firstSparkline = fWorksheet.addSparkline(
  [fWorksheet.getRange('A1:A7').getRange()],
  [fWorksheet.getRange('A10').getRange()],
)

// Create a sparkline with data source from B1:B7, placed in cell B10.
const secondSparkline = fWorksheet.addSparkline(
  [fWorksheet.getRange('B1:B7').getRange()],
  [fWorksheet.getRange('B10').getRange()],
)
console.log('Cell A10: ', fWorksheet.getSparklineGroupByCell(9, 0))

// After 3 seconds, compose the two sparklines into a sparkline group
setTimeout(() => {
  fWorksheet.composeSparkline([fWorksheet.getRange('A10:B10').getRange()])
  console.log('Cell A10: ', fWorksheet.getSparklineGroupByCell(9, 0))
}, 3000)
```

[`FSparkline`](https://reference.univer.ai/en-US/classes/FSparkline) instance has the following methods to manipulate the sparkline:

| Method | Description |
| --- | --- |
| changeDataSource | Modify the data source and placement of the sparkline in the current cell
| removeSparkline | Remove the sparkline in the current cell |

[`FSparklineGroup`](https://reference.univer.ai/en-US/classes/FSparklineGroup) instance has the following methods to manipulate the sparkline group:

| Method | Description |
| --- | --- |
| changeDataSource | Modify the data source and placement of the sparkline group in the current cell
| removeSparklineGroup | Remove the sparkline group in the current cell
| setConfig | Change the configuration of the sparkline group in the current cell |

### Event Listeners

Complete event type definitions can be found in the [Events](https://reference.univer.ai/en-US/classes/FEventName).

`univerAPI.Event.SheetSparklineChanged` event is triggered when the sparkline changes.

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetSparklineChanged, (params) => {
  const { workbook, worksheet, sparklines } = params
})

// Remove the event listener, use `disposable.dispose()`
```
